Style_guide

Introduction to Document360 style guide

What is a document style guide?

A document style guide contains a set of instructions, guidelines, and standards for writing and presenting the content. It can be a valuable resource for editors, authors, and other content creators.A style guide in general can help you write clearly and concisely, avoid common mistakes, and present your content in an appealing way. You can use it as a reference when creating or editing your own content, or as a guideline for the content of others.

Document360 style guide

The Document360 style guide is tailor-made to set a standards for the documentation and content used for the brand Document360 and other products in the Kovai.co umbrella.

Internal article link

Anchored link

Internal article link

Grammar

Basics

Write for all readers

Some people will read every word you write. Others will just skim. Help everyone read better by grouping related ideas together and using descriptive headers and subheaders.

Focus your message

Create a hierarchy of information. Lead with the main point or the most important content, in sentences, paragraphs, sections, and pages.

Be concise

• Use short words and sentences

• Avoid unnecessary modifiers

Be specific

Avoid vague language. Cut the fluff.

Be consistent

Stick to the copy patterns and style points outlined in this guide.

Voice

Use active voice. Avoid passive voice.

Active voice: The subject of the sentence performs the action.
Passive voice: The subject of the sentence has been acted upon.

Words like “was” and “by” may indicate that you are writing in passive voice. Check for these words in your document and rephrase the occurrences, if required.

One exception is when you want to specifically emphasize the action over the subject. In such cases, it is good to write in passive voice.

For example, Your account was blocked by our security team.

Capitalization

We use few different forms of capitalization.

Title case capitalizes the first letter of every word except articles, prepositions, and conjunctions.

Sentence case capitalizes the first letter of the first word.

Recommended

• Use sentence case for the titles and headings

• Use sentence case for the paragraphs

• Use lowercase for email address and website URL

[email protected]
churn360.com

• Keep the capitalization as per the specific software or product name, such as case-sensitive keywords or product or service names with internal capitalization

• Do not use capitalization randomly

• Use lowercase unless there is a specific reason for capitalizing

• When writing out an email address or website URL, use all lowercase

• Don't capitalize random words in the middle of sentences

Nouns

A noun is a word (other than a pronoun) used to identify any of a class of people, places, or things (common noun), or to name a particular one of these (proper noun).

• In general, form the plural of a noun by adding s. If the noun already ends in s, form the plural by adding es. This rule applies to proper nouns as well as common nouns.

Overview page - Overview pages
Product - Products

• Form the possessive of singular nouns and abbreviations by adding an apostrophe and an s. This rule applies even if the noun or abbreviation ends in s.

• Form the possessive of plural nouns that end in s by adding only an apostrophe. Form the
  possessive of plural nouns that do not end in s by adding an apostrophe and an s.

Knowledge base articles' performance
SSO configuration's UI has been made simple

Prepositions

Prepositions are words that show the relationship between a noun or pronoun and another word in a sentence. They are usually placed before a noun or pronoun to show its relationship to the rest of the sentence. Here are some common prepositions and their functions:

Location or position

• at

• on

• in

• under

• over

• behind

• beside

• between

The cat is under the table.

Time

• on

• at

• in

• for

• during

She arrived at the airport at 3 p.m.

Direction or movement

• to

• toward

• towards

• from

• into

• onto

• out of

He is walking to the store.

Possession or ownership

• of

• for

• by

The book is for Rachel.

Numbers

• Spell out whole-number words for one to ten

• Use figures for numbers above ten

You can create up to six levels of subcategories.
15 team accounts can be accommodated in a Business project.

Documentation structure

Hierarchy

The structure of a technical document can vary depending on the subject matter and intended audience. The below are the common elements:

1. Introduction: This section provides an overview of the document, outlining its purpose and scope.

2. Detailed technical information: This section provides more detailed information about the technical concepts and details covered in the document. This includes information about how to use a particular product or system, descriptions of technical processes or protocols, and so on.

3. Examples: This section provides examples of how to use the technical information presented in the document. Use cases of the feature can be added in this section.

4. References: This section provides references and resources for further information about the subject matter covered in the document. This may include links to related articles, tags, tutorials, and other resources.

Headings

Headings are used in technical documentation to organize and structure the content, making it easier for readers to find and understand the information they need. They also help to break up long blocks of text and make the document more visually appealing.

There are several types of headings that may be used in technical documentation, including:

Main headings
These are the highest-level headings in the document and are usually used to indicate the major sections or topics covered. They should be used sparingly and should be clearly distinguished from other headings.

Subheadings
These are used to further divide and organize the content within the main sections of the document. They should be used to introduce new ideas or topics and should be clearly related to the main heading.

Sub-subheadings
These are used to divide the content even further and provide additional detail on specific ideas or topics. They should be used sparingly and should be clearly related to the subheading under which they appear.

Lists
Lists are often used in technical documentation to present information in a clear and concise manner. They can be used at any level of the document hierarchy and can be used to highlight key points or to present a series of steps or procedures.

Rules

• Use sentence case for headings

• Use heading tags

• Do not use period for headings

• Use question mark and exclamation point if required

Tone

Rules:

The tone of a piece of writing or speech refers to the attitude that the writer has towards the topic or audience.

• Use formal tone in all places

• Use informal tone only in exceptional cases such as examples and use cases

• Use inclusive terminologies

Formal tone

Technical documentation is typically written in a formal tone. It is meant to be a clear and concise source of information for technical professionals. Here are some characteristics of a formal tone in technical documentation:

1. Objective: Technical documentation should be objective and unbiased, presenting information in a neutral manner. Personal opinions and subjective language should be avoided.

2. Precise: Technical documentation should be precise and accurate, using specific language to convey precise meanings. It is important to clearly define terms and avoid vague or ambiguous language.

3. Formal: Technical documentation should use formal language and avoid slang, colloquialisms, or jargon that may not be familiar to all readers.

4. Concise: Technical documentation should be concise and to the point, avoiding unnecessary information or filler words. It should focus on the key points and present them clearly and efficiently.

By maintaining a formal tone, technical documentation can effectively convey information to its intended audience and be a reliable source of technical knowledge.

Examples

1. The report shows the list of feedback received in the selected date range.

2. It works effectively for SSO readers.

Informal tone

It is recommended to not use an informal tone in technical documentation, as it is meant to be a professional, authoritative source of information for technical professionals. Technical documentation should be written in a formal tone to ensure that it is clear, concise, and accurate.

Using an informal tone in technical documentation can make it difficult for readers to understand. It is important to use precise language, avoid slang, colloquialisms, or jargon, and present information objectively to ensure that technical documentation is effective and reliable.

There may be some exceptions to this, such as when writing documentation for a consumer audience or when using a more conversational style to explain complex concepts in a more approachable way. However, even in these cases, it is important to maintain a level of professionalism and avoid using language or tone that may be inappropriate or confusing for the intended audience.

Examples
Many 404-error pages would mess up the domain health.
I was wondering if I can buy your products.

Vocabulary

Business terms

Each technical domentation will have set of business terms. These terms can be added as a glossary section.

• Compile the terms: Compile the list of terms in a separate page and provide a minimum of one-line description for each term.

• Visibility: Ensure that the list is visible for your readers.

• Components: The list must contain the following sections- Term name, Part of speech (noun, verb, or adjective), Example sentence

Punctuations

Apostrophe

The apostrophe's most common use is making a word possessive. It can also denote the omission of some letters from a word.

Singular

Add an apostrophe (') and an 's' at the word's end to make the singular noun possessive. You can use this even if the word ends with an 's'.

Plural

Add 's' or 'es'. If the word ends with 's', add an apostrophe.

Don'ts

• Don't use an apostrophe to form a plural noun. In most cases, you should add an "s" to create a plural noun

For example, "feature" becomes "features," not "feature's".

• Don't use an apostrophe to form the possessive in case of a singular noun that ends in 's'.

For example, "James' book" is incorrect; it should be "James's book."

• Don't use an apostrophe to form a possessive pronoun.

For example, Possessive pronouns like "mine," "yours," and "theirs" do not require an apostrophe.

Colon

A colon is used to introduce a list, a statement, or an explanation. It is typically used to introduce something that follows it, such as a list of items, a quotation, or a summary.

• Use a colon to introduce a list of items, especially if the list is long or complex.

• Use a colon to introduce an explanation or expands upon the information that precedes it.

• Start the word with lowercase after a colon within the same sentence. You can ignore for the following scenarios:

  • It introduces a direct quotation

  • The first word after the colon is a proper noun

Comma

A comma is used to indicate a pause or break in a sentence. It is often used to separate clauses, words, or phrases within a sentence. In a list of three or more items, use a oxford (serial) comma before the conjuction. It is used to clarify the meaning of a list, especially when the items in the list are complex.

• Use a comma to separate three or more elements in a sentence

• Use a comma to separate independent clauses when they are joined by a conjunction

• Use a comma after an introductory phrase or clause

Dash and Hyphen

Dashes and hyphens are used to indicate breaks or pauses in a sentence or to join words together. However, they have different uses and should be used appropriately.

• Use a hyphen (-) to join two or more words together to form a compound word such as "Single Sign-On or "check-in"

• Use an em dash (—) without spaces on either side to offset an aside

• Use a true em dash, not hyphens (- or --)

Ellipses

Ellipses (...) can be used to indicate that you’re trailing off before the end of a thought. Use an ellipsis to show that some text is missing, usually from a quotation.

• Do not surround it with spaces

• Use them sparingly

• Do not them in titles or headers

Examples
It is a truth universally acknowledged…
Did he say that…?
We could do this…or maybe that…

Exclamation point

Use exclamation points sparingly, and never more than one at a time. They’re like high-fives: A well-timed one is great, but too many can be annoying.

• Use it inside quotation marks

• Use it outside parentheses when the parenthetical is part of a larger sentence

• Use it inside parentheses when the parenthetical stands alone

• Use it in titles if required

• Do not use it in failure messages or alerts

Examples
Wait for me!
You don’t have to be mad to work here… but it helps!

Period

• Use it inside quotation marks

• Use it outside the parentheses when the parenthetical is part of a larger sentence

• Use it inside parentheses when the parenthetical stands alone

• Use only one space after a period

• Do not use it at the end of the list

• Do not use it in titles

Question mark

• Use it inside quotation marks if they’re part of the quote

• Use it outside parentheses when the parenthetical is part of a larger sentence

• Use it inside parentheses when the parenthetical stands alone

• Use it titles if required

Quotation mark

• Use it to refer specific terms and actions done in the product

• Use closing quotation marks outside commas and periods

• Use it for text/message that appears on the screen

• Use it for text/message that is written on the product

Examples
What is "SEO description generator"?
The "Issue resolved" message appears

Text formatting

Basic formatting (Bold, Italic, Underline, Strikethrough)

1.Bold

Bold text is used to draw attention to important words or phrases and make them stand out. It is often used to highlight headings, subheadings, or key points.

2.Italic

Italic text is used to emphasize a word or phrase, or to indicate a foreign word or term. It is often used to distinguish between different types of text, such as titles or book names.

3.Underline

Underline is used to indicate a hyperlink or to draw attention to a specific word or phrase. It is important to use underline sparingly, as it can be difficult to read if used excessively.

4.Strikethrough

Strikethrough is used to indicate that a word or phrase is no longer applicable or has been removed. It is often used in documents that are being edited or revised to show what changes have been made.

Blockquote

A blockquote is used to set off a quote or passage of text from the rest of the document. In technical documentation, blockquotes are often used to highlight important information or to show examples of how something should be done.

Example:

For example, you can use this feature to compare the performance of each individual in a team.

Using blockquotes in technical documentation helps to distinguish between different types of text and draw attention to important information.

Code blocks

Code blocks are used in technical documentation to set off blocks of code or programming language from the rest of the text. They are used to clearly show examples of how to write code or to explain how a particular programming concept works.

Code blocks are typically formatted differently from the rest of the text, using a monospaced font and syntax highlighting to make the code easier to read and understand. A copy option would be available to easily reuse it in the desired space.

Example:

def greet(name):
    print("Hello, " + name)
    
greet("John")

The syntax highlighting and monospaced font help readers understand the code.

Callouts

Callouts are used to draw attention to specific information or to provide additional context or explanations for a particular concept or procedure. Callouts are often used to highlight important points, provide examples, or give cautionary notes or warnings.

There are several different types of callouts that can be used in technical documentation, including notes, tips, warnings, errors, and examples.

1. Notes: Notes are used to provide additional information or context on a particular topic. They may be used to explain a concept in more detail or to provide guidance on how to apply the information to a specific situation.

2. Tips: Tips are used to provide helpful hints or suggestions that may make a task easier or more efficient. They may be used to provide best practices or recommend specific tools or techniques.

3. Warnings: Warnings are used to alert readers to potential hazards or risks associated with a particular procedure or task. They may be used to caution readers about potential risks or to provide instructions on how to avoid them.

4. Errors: Errors are used to indicate problems or issues that may arise when using a product or system. They may be used to alert readers to issues that could cause the system to malfunction or to provide instructions on how to troubleshoot or fix the problem

5. Examples: Examples are used to illustrate a concept or procedure with a specific example. They may be used to show how a particular code snippet works or to demonstrate how to use a particular tool or feature.

Private notes

Private notes are intended for the author or editor of a document. It is not meant to be shared with readers. It is typically used to record ideas, observations, or questions that the author or editor may have while working on the document.

It can be included in technical documentation for a variety of reasons.

For example, an author may use private notes to record ideas for future revisions of the document, to flag sections of the document that need further clarification or editing, or to keep track of tasks that need to be completed.

It is not visible to readers of the document and are usually hidden or removed before the document is published or shared.

Links

Links are used to provide readers with quick access to additional information or resources related to a particular topic. It is usually highlighted in blue and underlined. When a reader clicks the link, a webpage or location within the document appears.

There are three types of hyperlinks that can be used in technical documentation:

1. External links: External links are links to websites or resources that are not part of the product documentation. They are used to provide readers with access to additional information or resources related to a particular topic.

2. Internal links: Internal links are links to different sections or pages within the product documentation. They are used to help readers navigate the document and quickly find specific information.

3. Anchor links: Anchor links are links that take the reader to a specific location within the same webpage or document. They are often used to create a table of contents or to provide quick access to specific sections of a document.

Language

Inclusiveness is the practice of ensuring that the document is accessible and understandable to a diverse audience, including people with different backgrounds, experiences, and abilities.

Best practices

1. Use plain language
   Technical documentation can be written in a way that is accessible to readers who may not have a technical background. This can be achieved by using plain language and avoiding jargon, technical terms, or complex sentence structures.

2. Include alt text for images
   Alt text is a description of an image that is displayed when the image cannot be displayed. Adding it allows people with visual impairments to understand the content of the image.

3. Use headings and subheadings
   Headings and subheadings help to break up the text and make it easier to scan and understand. They also help people using assistive technology, such as screen readers, navigate the document more easily.

4. Provide examples
   Adding examples can help readers understand and apply the information being presented. It is important to provide examples that are relevant and relatable to a diverse audience.

Tense

Present tense is generally recommended in the technical documentation, as it helps to convey a sense of immediacy and makes the information feel more current and relevant.

Examples

Instructions
When providing instructions or procedures, it is usually best to use present tense to make it clear that the steps should be followed in the present.

For example, To install the software, download the installation file from the website and double-click the file to start the installation process.

Descriptions
When describing features or characteristics of a product or system, present tense is typically used to convey a sense of what the product or system can do in the present.

For example, The feature allows users to create and edit documents easily.

Definitions
When defining terms or concepts, present tense is usually used to describe the meaning or characteristics of the term in the present.

For example, A category is a collection of subcategories and articles.

Variables

Date and Time

Date

• Use only the first three letters for the month name

• Do not use 'th', 'st', 'nd' or 'rd' next to the date

• Add a comma next to the date

• Add only one space between comma and year

Time

• Keep the timing in a common standard

For example, use UTC for all instances

• Use 24-hour timing format

• Do not use AM or PM next to the time

Currency and numbers

• Add the currency at the beginning

• Use decimal when you mention about cents or similar values

• Do not add a space between symbol and number

For example, To indicate the US currency, use the dollar sign before the amount. If the number of cents is more than 0, use a decimal.

• $20

• $19.99

Email and third-party links

Email and third-party links provide readers with additional resources or contact information that may be relevant to the topic being discussed. It is important to carefully evaluate the credibility and relevance of any third-party resources before including them in the documentation

Examples

1. Contact information: Including an email address can provide readers with a way to contact the author or editor of the document with questions or comments. It can also provide readers with a way to request additional information or resources.

2. Third-party resources: Including third-party links can help readers to get information on relevant topics in the article.

3. Support: Including email addresses or third-party links to support resources can help readers troubleshoot problems or get help with specific issues.